Inside Macintosh: QuickTime Components /

Chapter 9 - Movie Data Exchange Components / Movie Data Exchange Components Reference

Importing Movie Data /

MovieImportHandle

The MovieImportHandle function allows the Movie Toolbox to import data from a handle, using your movie data import component.

pascal ComponentResult MovieImportHandle (ComponentInstance ci,
                                       Handle dataH, 
                                       Movie theMovie, 
                                       Track targetTrack,
                                       Track *usedTrack,
                                       TimeValue atTime,
                                       TimeValue *addedDuration, 
                                       long inFlags, 
                                       long *outFlags);

ci

Identifies the Movie Toolbox's connection to your movie data import component.

dataH

Contains a handle to the data that is to be imported into the movie identified by the parameter theMovie. The data contained in this
handle has a data type value that corresponds to your component's subtype value.

Your component is not responsible for disposing of this handle.

theMovie

Identifies the movie for this operation. This movie identifier is supplied by the Movie Toolbox. Your component may use this identifier to add sample data to the target movie, or to obtain information about the movie.

targetTrack

Identifies the track that is to receive the imported data. This track identifier is supplied by the Movie Toolbox and is valid only if the movieImportMustUseTrack flag in the inFlags parameter is set to 1.

usedTrack

Contains a pointer to the track that received the imported data.
Your component returns this track identifier to the Movie Toolbox. Your component needs to set this parameter only if you operate on a single track or if you create a new track. If you modify more than one track, leave the field referred to by this parameter unchanged.

atTime

Specifies the time corresponding to the location where your component is to place the imported data. This time value is expressed in the movie's time coordinate system.

addedDuration

Contains a pointer to the duration of the data that your component added to the movie. Your component must specify this value in the movie's time coordinate system.

inFlags

Specifies control information governing the import operation. The following flags are defined:

movieImportCreateTrack

Indicates that your component should create a new
track to receive the imported data. You must create a track whose type value corresponds to the media type that you have specified in your component's manufacturer code. You should return the track identifier of this new
track in the field referred to by the usedTrack
parameter, unless you create more than one track. If you create more than one track, be sure to set the movieImportResultUsedMultipleTracks flag (in the field referred to by the outFlags parameter) to 1.

If the movieImportCreateTrack flag is set to 1, then the movieImportMustUseTrack flag is set to 0.

movieImportMustUseTrack

Indicates that your component must use an existing track. That track is identified by the targetTrack parameter. If you create more than one track, be sure to set the movieImportResultUsedMultipleTracks flag (in the field referred to by the outFlags parameter) to 1.

If the movieImportMustUseTrack flag is set to 1, then the movieImportCreateTrack flag is set to 0.

If both the movieImportCreateTrack and movieImportMustUseTrack flags are set to 0, then you are free to use any existing tracks in the movie or to create a new track (or tracks) as needed.

movieImportInParallel

Indicates whether you are to perform an insert operation or a paste operation. If this flag is set to 0, then you should insert the imported data into the target track. If this flag is set to 1, then you should add the imported data to the track, overwriting preexisting open space currently in
the track. Note that an application may use the MovieImportSetDuration function (described on page 9-27) to control the amount of data you paste into a movie.

If the movieImportMustUseTrack flag is set to 1, then you should use the track specified by the targetTrack parameter. If this is not possible, return an appropriate Movie Toolbox result code.

outFlags

Contains a pointer to a field that is to receive status information about the import operation. Your component sets the appropriate flags in this field when the operation is complete. The following flags are defined:

movieImportResultUsedMultipleTracks

Indicates that your component modified more than one track in the movie. Set this flag to 1 if your component places imported data into more than one track. In this case, you do not need to update the field referred to by the usedTrack parameter.

movieImportInParallel

Indicates whether you performed an insert operation or a paste operation. Set this flag to 0 if you inserted the imported data into the target track. Set this flag to 1 if you added the imported data to the track, overwriting preexisting open space currently in the track.

DESCRIPTION

The Movie Toolbox calls the MovieImportHandle function in order to import movie data from a handle. The data stored in the handle has a data type that corresponds to the component subtype of your movie data import component. Your component must read the data from the supplied handle, perform appropriate conversions on that data, and place the data into the movie.

If your component can accept data from a handle, be sure to set the canMovieImportHandles flag in your component's componentFlags field.

Your component must be prepared to perform this function at any time. You should not expect that any of your component's configuration functions will be called first.

RESULT CODES

invalidTrack

-2009

Specified track cannot receive imported data

Other appropriate Movie Toolbox result codes

SEE ALSO

The Movie Toolbox uses the MovieImportFile function to import data from a file; this function is described next.

Main | Top of Section | What's New | Apple Computer, Inc. | Find It | Feedback | Help